System Booster/System Booster.iso/Archives/ARexxTools/VerCtrl_1_16.lha/VerCtrl.doc

Text File | 1995-08-05 | 9.1 KB | 227 lines

/*----------------------------------------------------------------------*/
                            VerCtrl.rexx v1.16

                An AREXX development environment for Opus5

              by Dave Freeman ([e-mail])

/*----------------------------------------------------------------------*/


Description:
~~~~~~~~~~~~

The contents of this archive form the basis of my own AREXX development
environment.  It provides a method for creating new projects and for
managing projects under way such that version information is maintained in
an AmigaDOS compliant way (i.e. the AmigaDOS 'Version' command works on my
AREXX scripts).

This system also provides an easy way for me to start a new project with a
script that already contains the basic layout that I normally use including
such things are error trapping, readargs() style argument handling and
other procedures and concepts that I like to use.


Requirments:
~~~~~~~~~~~~

To fully install and use the contents of this archive you will need the
following:

         AREXX - part of AmigaDOS since release 2
         DirectoryOpus v5 - I use v5.11
         CygnusEd Text Editor - I use v3.5
         rexxdossupport.library v2.3 by hartmut Goebel


I have included RexxDosSupport.lha in the 'Extras' directory of this
archive but it can also be found on AmiNet in util/rexx if you are looking
for a different version or whatever.

While I list these as requirements it would not be difficult to modify the
contents of this archive to suit just about any environment with the
exception of the need to have AREXX to write AREXX scripts.  :)


Installation:
~~~~~~~~~~~~~

I will describe my own setup here.  It should make it fairly obvious what
you will need to change to suit your own particular needs on your own
machine.

1.  Create a directory to store your AREXX projects.  Sub-directories will
be created as required.  i.e.  Work:RexxDev

2.  Move VerCtrl.rexx to the directory you have just created (or anywhere
else that you want to call it from really, it doesn't really need to be
anywhere in particular).

3.  Move RexxProg.rexx to your REXX: directory.

4.  Copy the included RexxDosSupport.library to LIBS:

5.  Copy Images/EdRexx.small to DOpus5:Images (I know, it's not much of an
image - perhaps some artist out there can improve it <g>).

6.  Edit your Lister ToolBar (Menu -> Lister -> Edit Lister Toolbar...) and
add a new button (Add gadget).

7.  Edit the new button you just created.  Add the EdRexx.small button as
the image.

8.  On the LMB I use the following:

    Function:
    ARexx          Work:RexxDev/VerCtrl.rexx (ou) {s}
    AmigaDOS       Work:CygnusEd/Ed {f}

    Flags:         CD source
                   No file quote

9.  On the RMB I use the following:

    Function:
    ARexx          Work:RexxDev/VerCtrl.rexx {RsEnter New AREXX Project
                                               name...:Test.rexx} {s} New
    AmigaDOS       Work:CygnusEd/Ed `GetENV RexxDev.File`
    AmigaDOS       UnSetENV RexxDev.File

    Flags:         CD source
                   No file quote
                   Rescan source

10. That's pretty much it for my standard installation.


What it does:
~~~~~~~~~~~~~

VerCtrl.rexx is the main control script.  It takes three arguments.  The
first argument is the name of the file to edit (it does not _have_ to end
in '.rexx' but '.rexx' will be added to it if there is no other extension -
an extension, in this case, is defined as any filename that has at least
one period '.' in it).  The second argument is the path contains the file
you wish to edit.  This path should exist, obviously, since you are going
to edit a file in that path.  If you are creating a new project then you
use the 'New' switch.  The third argument is a switch that lets you tell
VerCtrl.rexx to create a new directory for this project - the switch is
optional.

When VerCtrl.rexx is invoked it will look for the given file in the given
directory.  If the file is not found then the script will fail.  If you are
using this script from Opus5 then you will normally be running this script
from a button so failure is not likely in this case.  If the 'New' switch
is also given then a new project will be created.  This new project will be
created in a new directory.  The new directory will be created as a
sub-directory of the current directory.

It is the creation of this new AREXX script that REXX:RexxProg.rexx is used
for.  This is the script that forms the basis for most of the AREXX scripts
that I write.  It contains elements that I like to have in all of my AREXX
scripts.  If you always want to include other items in your AREXX script
then add them to this file.  You can change anything you like in the script
as long as you retain certain elements.  Basically, VerCtrl.rexx writes a
new version string in two places every time it is used.  I use a standard
format for the first few lines of my AREXX programs as follows:

  -----8<-----
1-  /*\
2-   *
3-   *  $VER:
4-   *
5-  \*/
6-
7-  VersMsg =
8-  Author  = "Dave Freeman"
9-  Contact = "[e-mail]"
  -----8<-----

Line 3 and line 7 are altered by VerCtrl.rexx each time it is executed.
These two lines are identified by a search for ' *  $VER:' and 'VersMsg = '
respectively.  You should avoid having any other matches for these two
strings in your own scripts.  It does not matter where in the script these
two lines end up being, they will be found and altered.

I like to be able to easily output an information message in some programs
and the two variables Author and Contact are set for my use.  You should
alter them accordingly to suit your own particular needs.

In general I would suggest that you make any changes to the comment block
at the start of the program at a point after line 3 and leave line 1 and
line 5 in their current format (just copy line 4 and add comments on a line
similair to that one as required).

When used from Opus5 the final result will be that you can click on an
AREXX script and use VerCtrl.rexx to search out the AmigaDOS version string
and increment the revision number and set the date to today's date
(assuming your system clock is correct).  It will then load that file into
your text editor ready for you to continue development.

If you want to create a new AREXX project just click on the toolbar button
with the right mouse and it will prompt for a new project name to create.
VerCtrl.rexx will then create the new directory and place a new AREXX
script of the required name in that directory.  The new script will have a
valid AmigaDOS version string and will contain whatever you have in the
'shell' AREXX script 'REXX:RexxProg.rexx'.

A new feature with v1.15 is the ability to use multiple 'shell' AREXX
scripts.  This enables you to, for example, have a 'shell' AREXX script for
developing scripts for DOpus5 and another one for use in AmigaDOS shells
and another for use with a BBS program and so on.  Each 'shell' script is
identified by it's extension in much the same way that CygnusEd identifies
the appropriate environment to load.  In this case, VerCtrl.rexx will first
look for REXX:RexxProg.extension where extension will match whatever
follows the LAST period '.' in the given filename (.dopus5 or .ced or
whatever) and will then default to 'REXX:RexxProg.rexx' if the preceeding
search fails.

Limitations:
~~~~~~~~~~~~

The current setup requires a fairly strict hierarchy of directories within
your development directory path.  I am working on a way to improve this at
the moment.  I see it as a 'good thing' (tm) to keep development scripts in
a directory of it's own anyway since this helps to keep bits together and
leaves a logical point to create a distribution archive or store
documentation and development notes or other ancilliary files associated
with that project that may change regularly while development continues.

(Note: This limitation has been made somewhat more flexible.  You can now
edit any script in any directory by select/click and can create a new
project as a directory in the current path.  In my own use, this is about
as far as I want to take this particular 'limitation' so if you want other
capabilities in this respect, please let me know - or fix it yourself...
<g>).

Feedback:
~~~~~~~~~

If you have any suggestions or ideas on this project please feel free to
get in touch.  I'll implement anything that looks like a good idea to me.
<grin>  Development work is ongoing as this is the environment that I
currently use to write my own AREXX scripts and as and when I see a way to
enhance the setup I make the required alterations.

I can be reached in the following ways:

      Usenet:    [e-mail] (Preferred)
                 [e-mail] (If the above does not work)

         IRC:    dfreeman (If you happen to see me - I'm not on all that
                           often)

     FIDONet:    3:640/535  - Dave Freeman
    AmigaNet:    41:450/533 - Dave Freeman


Distribution:
~~~~~~~~~~~~~

This project is currently freely distributable but I maintain the rights to
the scripts included.  If you alter the function of these scripts in any
way please forward a copy of your changed script to me via one of the above
methods.